QuickTime 3 Reference
| Previous | Chapter Contents | Chapter Top |
This section defines the effect-specific functions that you may supply in your effect components. This section is only of interest to developers who are creating their own effects components; if you are writing an application that uses QuickTime Video Effects, you can skip this section.
The functions defined in this section are those called by the Component Manager through your component's dispatch function (see "What Effects Components Do" ).
The interfaces to these functions are described assuming you are using Apple's component dispatch helper code and sample effect Framework as described in "The Sample Effect Component" . Apple strongly recommends that you re-use these code samples where possible when implementing your own effect components.
If you are using the sample effect component, you can use the default implementations of several of these functions in most circumstances.
The Component Manager calls this function when a sequence of frames is about to be rendered.
ComponentResult MyEffectSetup(
EffectGlobals *glob,
CodecDecompressParams *decompressParams);
This function is called immediately before a client application (which may be QuickTime) is going to call your component to render a sequence of frames of your effect.
Your component should examine the capabilities field of the decompressParams data structure to ensure that it can meet the requirements for executing this sequence. In particular, it should check the bit depth and pixel format requirements of the sequence. If the sequence requires a bit depth and pixel format combination that your component does not support, this function should return the nearest supported combination in the decompressParams->capabilities field. In this case, QuickTime will redirect all source and destination bitmaps through offscreen graphics worlds that have the bit depth and pixel format characteristics that you specify.
The Component Manager calls this function to request that your component prepare to render a single frame of its effect.
ComponentResult MyEffectBegin(
EffectGlobals *glob,
CodecDecompressParams *decompressParams,
EffectsFrameParamsPtr effect);
This function is called by a client application (which may be QuickTime) immediately before your MyEffectRenderFrame function. Your MyEffectBegin function should ensure that the information it holds about the current source and destination buffers and the parameter values for the effect are valid. If any of these have changed since the last call to MyEffectBegin , the new values should be read from the appropriate data structures.
This function is guaranteed to be called synchronously. In particular, this means you can allocate and move memory, and call functions that allocate or move memory.
The Component Manager calls this function to request that your component render a single frame of its effect.
ComponentResult MyEffectRenderFrame(
EffectGlobals *glob,
EffectsFrameParamsPtr effect);
This function is called by a client application (which may be QuickTime) when your effect component needs to render a single frame of your effect. This function contains the implementation of your effect.
This function is not guaranteed to be called synchronously. In particular, this means your function implementation must not allocate or move memory, or call any function that allocates or moves memory.
The Component Manager calls this function to stop processing of the current effect.
ComponentResult MyEffectCancel(
EffectGlobals *glob,
EffectsFrameParamsPtr effect);
This function is called by a client application (which may be QuickTime) to halt the rendering of the current sequence of frames before the last frame has been rendered. If your component is running synchronously, it should simply return noErr ; no further calls to your MyEffectRenderFrame function will be made for this sequence.
If your component is running asynchronously, this function should dequeue all outstanding render frame requests, then return noErr .
The Component Manager calls this function to request information about the component.
ComponentResult MyEffectGetCodecInfo(
EffectGlobals *glob,
CodecInfo *info);
This function is called by a client application (which may be QuickTime) to request information about your effect component. Your function should fill out the CodecInfo data structure passed to it. You can use the GetComponentResource function to retrieve a 'cdci' resource that stores this information, if you have provided one in your component.
The Component Manager calls this function to request a parameter description for this component.
ComponentResult MyEffectGetParameterListHandle(
EffectGlobals *glob,
Handle theHandle);
The Component Manager calls this function to request information about the rendering speed of this effect component.
long MyEffectGetSpeed(
EffectGlobals *glob,
QTAtomContainer parameters,
Fixed *pFPS)
This function is called by a client application (which may be QuickTime) to request information about the rendering speed of your effect. This function should return a Fixed value in pFPS , which represents the rendering speed in frame per second of the effect.
If your effect can render in real time, it should return a value of effectIsRealtime . Otherwise, you should return an estimate of the number of frames your effect can render per second. Because rendering speeds are hardware-dependent, effect authors can choose to measure actual rendering speeds in this function. Alternatively, effect authors can choose to return a single value for all hardware configurations, estimating the value for a reference hardware platform.
Apple recommends that the values returned are rounded down to the nearest common frames-per-second value, such as 15, 24 or 30.
If your effect implements this optional function, the Component Manager calls it whenever the user changes a parameter value in the standard parameter dialog box, or attempts to dismiss the dialog.
ComponentResult MyEffectValidateParameters(
EffectGlobals *glob
QTAtomContainer parameters,
QTParameterValidationOptions validationFlags,
StringPtr errorString);
This optional function is called by a client application (which may be QuickTime) when your effect's standard parameter dialog box is being displayed. It can be called in two circumstances: if the user changes a parameter value in the dialog box; if the user dismisses the dialog box.
The purpose of this function is to allow your effect to validate its parameters. The current parameter values are passed to the effect in parameters . If all of these values are valid, this function should return noErr . Otherwise, you should return a paramErr and put an explanatory message in the errorString parameter.
| Previous | Chapter Contents | Chapter Top |